Get starting
- First, you must have Node.js installed on your computer.
- Extract the downloaded package from the marketplace.
- Start terminal and go to
/template/{variation}/directory from the package that was extracted. - This template uses Gulp as a task runner that helps you automate your time-consuming tasks in the development workflow. To install Gulp globally, you need to run
npm install --global gulp-cli. - Install all dependencies needed by running
npm install. - Run
gulp --versionto verify that Gulp is successfully installed, and the version of installed Gulp will appear and make sure you have installed Gulp 4.x version. - Try to run
gulp buildon the terminal to build all assets. - Start the development server by running
gulp serveand keep the terminal open and visit the link on the terminal. The server will automatically build assets and reload the browser if you edit the source codes. PressCTRL+Cto stop the server.
Directory structure
This template comes with a simple and organized directory structure for easy to understand and maintainability. Look at the treeview below to find the basic template directory structure.
Template directory
- dist - contains compiled code and assets
- assets - contains all assets for supporting the pages
- app - contains compiled app scripts
- build - contains all compiled library assets
- scripts - contains compiled library JS files
- styles - contains compiled library CSS files
- fonts - contains fonts
- images - contains images
- *.html - HTML pages from compiled Nunjucks
- assets - contains all assets for supporting the pages
- src - contains source code and assets
- app - contains source app scripts
- assets - contains all additional assets
- build - contains buildable library assets
- core - contains Bootstrap and core component source codes
- vendors - contains custom 3rd party library source codes
- pages - contains source Nunjucks codes
- tool - contains build tool scripts
- config.json - build configuration
- gulpfile.js - Gulp main script
Build tools
This template uses Gulp to power the build tools. The build tool provides an easy way to organize, compile, and bundle assets. Below are all the build tool commands.
| Command | Description |
gulp clean | Delete dist/ directory |
gulp assets | Copy all additional assets such as images, fonts that linked on config.json or inside src/assets/ into dist/assets/ directory |
gulp build:style-core | Compile and bundle Bootstrap and core SCSS files that linked under build.core.styles object in config.json to (ltr|rtl)-core.css |
gulp build:style-vendor | Compile and bundle 3rd party library SCSS files that linked under build.vendors.optional.[package-name].styles object in config.json to (ltr|rtl)-vendor.css |
gulp build:style | Run all SCSS build tasks: gulp build:(style-core|style-vendor) |
gulp build:script-core | Bundle Bootstrap and core JS files that linked under build.core.scripts object in config.json to single file core.js |
gulp build:script-mandatory | Bundle mandatory library JS files that linked under build.vendors.mandatory.[package-name].scripts object in config.json to single file mandatory.js |
gulp build:script-vendor | Bundle 3rd party library JS files that linked under build.vendors.optional.[package-name].scripts object in config.json to single file vendor.js |
gulp build:script-app | Compile with Babel all JS files in src/app/ and moved into dist/assets/app/ directory |
gulp build:script | Run all JS build tasks: gulp build:(script-core|script-mandatory|script-vendor|script-app) |
gulp build:page | Compile all Nunjucks page codes in src/pages/public/ and moved into dist/ directory |
gulp build | Run all build tasks gulp (build:style|build:script|build:page|assets) parallelly |
gulp serve | Start the development server and watch source codes for live reloading. Press CTRL+C to stop the server |
Configuration
All build tool configurations are located at config.json and you can customize the configuration.
| Field | Type | Description |
config.port | integer | Local development server port |
config.production | boolean | Enable/disable production mode. By default, this option is false to speed up live reload. If you want to build for deployment, you must enable this option |
config.css_style | string | CSS output structure, you can set this option with nested|expanded|compact|compressed |
config.html_beautify | boolean | Beautify compiled HTML files. You can disable this option if you want to increase build tool performance. This option will be automatically disabled if you enable production mode |
config.sourcemaps | boolean | Enable/disable sourcemap. This option will be automatically disabled if you enable production mode |
config.skip | array | An array of 3rd party libraries to be skipped from being compiled, you can skip the libraries under build.vendors.optional. example: ["apexcharts", "autosize", "datepicker"] |
config.path | object | Collection of paths |
config.output | object | An object of build output file names |
build.core | object | The object specifies Bootstrap and core buildable assets |
build.vendors | object | The object specifies 3rd party library buildable assets |
build.vendors.mandatory | object | Assets list under this node is required, you can't skipped to be compiled |
build.vendors.optional | object | Assets list under this node can be skipped to be compiled |
Customization
Page
This template uses Nunjucks to generate HTML pages. Nunjucks provides many useful features like template inheritance, variables, modulation, and more to make your development easier. You can find all Nunjucks source codes in src/pages/ directory, look at tree view below to understand the directory structure.
Nunjucks source code directory src/pages/
- components - contains all supporting components
- [component] - contains specific page components
- template.njk - base template for inheriting
- variables.njk - Nunjucks general variables
- public - contains main pages that will be compiled
If you run the gulp build:page command, all Nunjucks files inside src/pages/public/ will be compiled and moved into dist/ directory. Don't make your pages from sketches, just start by customizing the prebuilt pages.
Tips: To set dark theme as default theme, you have to set defaults.theme variable in variables.njk with dark value.
Maybe your code editor doesn't support the jinja syntax highlighting of Nunjucks. There are plugins to support jinja syntax highlighting for some code editors.
- atom https://github.com/alohaas/language-nunjucks
- vim https://github.com/niftylettuce/vim-jinja
- brackets https://github.com/axelboc/nunjucks-brackets
- sublime https://github.com/mogga/sublime-nunjucks/blob/master/Nunjucks.tmLanguage
- emacs http://web-mode.org
- vscode https://github.com/ronnidc/vscode-nunjucks
Stylesheet
This template uses SCSS for handling the CSS efficiently. You can find all Bootstrap and core SCSS files in src/build/core/styles/. We remove several Bootstrap and core components because we replace them with our custom components. Find the custom 3rd party library SCSS files in src/build/vendors/(package-name)/styles/.
You can easily customize the color palette and other options by editing the variables in variables.scss.
SCSS source directory structure src/build/core/styles/
- components - contains component styles
- mixins - contains SCSS mixins
- utilities - contains utilities
- widgets - contains widgets
- _components.scss - concatenate all components
- _functions.scss - helper functions
- _mixins.scss - concatenate all SCSS mixins
- _reboot.scss - reset default page style
- _utilities.scss - concatenate all utilities
- _variables.scss - global variables
- _widgets.scss - concatenate all widgets
- index.scss - the main file to be compiled and concatenate all parts
Script
There are 2 types of the JS scripts: Bundlable script and App script. Bundlable script is all library scripts that will be bundled to a single file. App script is the script that is written for specific pages.
Bundlable script
Bundlable script is all JS files that are linked under build object in config.json. Bundlable scripts include all core and 3rd party library scripts, all the scripts will be bundled and moved into dist/assets/build/scripts/.
Find all Bootstrap and core component scripts in src/build/core/scripts/. This template takes 3rd party library scripts from node modules directory, but several library scripts have been customized. All the custom 3rd party library scripts are located inside src/build/vendors/(package-name)/scripts/.
App script
All app scripts are located in src/app/, all scripts inside this directory will be compiled with Babel and moved into dist/assets/app/. These scripts are written for a specific page. You can use ES6 syntax for these scripts.